More verbose documentation

diff --git a/gpsbabel/filter_skeleton.c b/gpsbabel/filter_skeleton.c
index 14bb2b02cfc58954a87b9389315c8c5fdcbd91a9..c3bea639032f8e2a03fb63050f667ecfdb97cc54 100644 (file)
--- a/gpsbabel/filter_skeleton.c
+++ b/gpsbabel/filter_skeleton.c
@@ -47,8 +47,14 @@ arglist_t filter_skeleton_args[] = {
 *******************************************************************************/
 
 static void
-filter_skeleton_init(const char *args)         /* optional.  If not needed, delete and replace entry in vecs with NULL  */
+filter_skeleton_init(const char *args)         
 {
+  /* Called before filter processing */
+       
+  /* optional.  If not needed, delete and replace entry in vecs with NULL  */
+  
+  /* This may be used to parse filter options, allocate memory, and do other
+   * housekeeping that should be done before filtering */
 }
 
 static void 
@@ -61,8 +67,29 @@ filter_skeleton_process(void)        /* this procedure must be present in vecs */
 }
 
 static void
-filter_skeleton_deinit(void)           /* optional.   If not needed, delete and replace entry in vecs with NULL*/
+filter_skeleton_deinit(void)           
 {
+  /* called after filter processing */
+       
+  /* optional.   If not needed, delete and replace entry in vecs with NULL */
+       
+  /* This should be used to clean up any memory allocations that are no longer
+   * needed after the filter terminates. */
+}
+
+static void
+filter_skeleton_exit(void)
+{
+  /* called on program exit */
+       
+  /* optional.   If not needed, delete and replace entry in vecs with NULL */
+       
+  /* You should not need this for simple filters, but it may be used to
+   * clean up memory allocations that must persist from one invocation of 
+   * your filter to the next (for example, the stack in the stack filter.) 
+   * Note that this member will be called even if your filter has not been
+   * used, so it *cannot* assume that _init or _process has been called
+   * previously. */
 }
 
 /*******************************************************************************/
@@ -71,7 +98,7 @@ filter_vecs_t filter_skeleton_vecs = {
        filter_skeleton_init,
        filter_skeleton_process,
        filter_skeleton_deinit,
-       NULL,
+       filter_skeleton_exit,
        filter_skeleton_args
 };